<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
<meta name="generator" content="pdoc 0.11.5" />
<title>pyboy.api.screen API documentation</title>
<meta name="description" content="This class gives access to the frame buffer and other screen parameters of PyBoy." />
<link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.0/normalize.min.css' rel='stylesheet'>
<link href='https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/8.0.0/sanitize.min.css' rel='stylesheet'>
<link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet">
<style>.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{font-weight:bold}#index h4 + ul{margin-bottom:.6em}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source summary,.git-link-div{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase}.source summary > *{white-space:nowrap;cursor:pointer}.git-link{color:inherit;margin-left:1em}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}.admonition{padding:.1em .5em;margin-bottom:1em}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:0.8em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.toc > ul > li{margin-top:.5em}}</style>
<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
<script async src='https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS_CHTML'></script>
</head>
<body>
<main>
<article id="content">
<header>
<h1 class="title">Module <code>pyboy.api.screen</code></h1>
</header>
<section id="section-intro">
<p>This class gives access to the frame buffer and other screen parameters of PyBoy.</p>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">#
# License: See LICENSE.md file
# GitHub: https://github.com/Baekalfen/PyBoy
#
&#34;&#34;&#34;
This class gives access to the frame buffer and other screen parameters of PyBoy.
&#34;&#34;&#34;

import numpy as np

from pyboy import utils
from pyboy.logging import get_logger

from .constants import COLS, ROWS

logger = get_logger(__name__)

try:
    from PIL import Image
except ImportError:
    Image = None


class Screen:
    &#34;&#34;&#34;
    As part of the emulation, we generate a screen buffer in 32-bit RGBA format. This class has several helper methods
    to make it possible to read this buffer out.

    If you&#39;re making an AI or bot, it&#39;s highly recommended to _not_ use this class for detecting objects on the screen.
    It&#39;s much more efficient to use `pyboy.PyBoy.tilemap_background`, `pyboy.PyBoy.tilemap_window`, and `pyboy.PyBoy.get_sprite` instead.
    &#34;&#34;&#34;

    def __init__(self, mb):
        self.mb = mb

        self.raw_buffer = self.mb.lcd.renderer._screenbuffer
        &#34;&#34;&#34;
        Provides a raw, unfiltered `bytes` object with the data from the screen. Check
        `Screen.raw_buffer_format` to see which dataformat is used. **The returned type and dataformat are
        subject to change.** The screen buffer is row-major.

        Use this, only if you need to bypass the overhead of `Screen.image` or `Screen.ndarray`.

        Example:
        ```python
        &gt;&gt;&gt; import numpy as np
        &gt;&gt;&gt; rows, cols = pyboy.screen.raw_buffer_dims
        &gt;&gt;&gt; ndarray = np.frombuffer(
        ...     pyboy.screen.raw_buffer,
        ...     dtype=np.uint8,
        ... ).reshape(rows, cols, 4) # Just an example, use pyboy.screen.ndarray instead

        ```

        Returns
        -------
        memoryview:
            92160 bytes memoryview of screen data.
        &#34;&#34;&#34;
        self.raw_buffer_dims = self.mb.lcd.renderer.buffer_dims
        &#34;&#34;&#34;
        Returns the dimensions of the raw screen buffer. The screen buffer is row-major.

        Example:
        ```python
        &gt;&gt;&gt; pyboy.screen.raw_buffer_dims
        (144, 160)

        ```

        Returns
        -------
        tuple:
            A two-tuple of the buffer dimensions. E.g. (144, 160).
        &#34;&#34;&#34;
        self.raw_buffer_format = self.mb.lcd.renderer.color_format
        &#34;&#34;&#34;
        Returns the color format of the raw screen buffer. **This format is subject to change.**

        Example:
        ```python
        &gt;&gt;&gt; from PIL import Image
        &gt;&gt;&gt; pyboy.screen.raw_buffer_format
        &#39;RGBA&#39;
        &gt;&gt;&gt; image = Image.frombuffer(
        ...    pyboy.screen.raw_buffer_format,
        ...    pyboy.screen.raw_buffer_dims[::-1],
        ...    pyboy.screen.raw_buffer,
        ... ) # Just an example, use pyboy.screen.image instead
        &gt;&gt;&gt; image.save(&#39;frame.png&#39;)

        ```

        Returns
        -------
        str:
            Color format of the raw screen buffer. E.g. &#39;RGBA&#39;.
        &#34;&#34;&#34;
        self.image = None
        &#34;&#34;&#34;
        Reference to a PIL Image from the screen buffer. **Remember to copy, resize or convert this object** if you
        intend to store it. The backing buffer will update, but it will be the same `PIL.Image` object.

        Convenient for screen captures, but might be a bottleneck, if you use it to train a neural network. In which
        case, read up on the `pyboy.api` features, [Pan Docs](https://gbdev.io/pandocs/) on tiles/sprites,
        and join our Discord channel for more help.

        Example:
        ```python
        &gt;&gt;&gt; image = pyboy.screen.image
        &gt;&gt;&gt; type(image)
        &lt;class &#39;PIL.Image.Image&#39;&gt;
        &gt;&gt;&gt; image.save(&#39;frame.png&#39;)

        ```

        Returns
        -------
        PIL.Image:
            RGB image of (160, 144) pixels
        &#34;&#34;&#34;
        if not Image:
            logger.warning(&#39;Cannot generate screen image. Missing dependency &#34;Pillow&#34;.&#39;)
            self.image = utils.PillowImportError()
        else:
            self._set_image()

        self.ndarray = np.frombuffer(
            self.mb.lcd.renderer._screenbuffer_raw,
            dtype=np.uint8,
        ).reshape(ROWS, COLS, 4)
        &#34;&#34;&#34;
        References the screen data in NumPy format. **Remember to copy this object** if you intend to store it.
        The backing buffer will update, but it will be the same `ndarray` object.

        The format is given by `pyboy.api.screen.Screen.raw_buffer_format`. The screen buffer is row-major.

        Example:
        ```python
        &gt;&gt;&gt; pyboy.screen.ndarray.shape
        (144, 160, 4)
        &gt;&gt;&gt; # Display &#34;P&#34; on screen from the PyBoy bootrom
        &gt;&gt;&gt; pyboy.screen.ndarray[66:80,64:72,0]
        array([[255, 255, 255, 255, 255, 255, 255, 255],
               [255,   0,   0,   0,   0,   0, 255, 255],
               [255,   0,   0,   0,   0,   0,   0, 255],
               [255,   0,   0, 255, 255,   0,   0, 255],
               [255,   0,   0, 255, 255,   0,   0, 255],
               [255,   0,   0, 255, 255,   0,   0, 255],
               [255,   0,   0,   0,   0,   0,   0, 255],
               [255,   0,   0,   0,   0,   0, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255, 255, 255, 255, 255, 255, 255, 255]], dtype=uint8)

        ```

        Returns
        -------
        numpy.ndarray:
            Screendata in `ndarray` of bytes with shape (144, 160, 4)
        &#34;&#34;&#34;

    def _set_image(self):
        self.image = Image.frombuffer(
            self.mb.lcd.renderer.color_format,
            self.mb.lcd.renderer.buffer_dims[::-1],
            self.mb.lcd.renderer._screenbuffer_raw,
        )

    @property
    def tilemap_position_list(self):
        &#34;&#34;&#34;
        This function provides the screen (SCX, SCY) and window (WX, WY) position for each horizontal line in the
        screen buffer. These parameters are often used for visual effects, and some games will reset the registers at
        the end of each call to `pyboy.PyBoy.tick()`.

        See `Screen.get_tilemap_position` for more information.

        Example:
        ```python
        &gt;&gt;&gt; pyboy.tick(25)
        True
        &gt;&gt;&gt; swoosh = pyboy.screen.tilemap_position_list[66:77]
        &gt;&gt;&gt; print(*swoosh, sep=newline) # Just to pretty-print it
        [0, 0, -7, 0]
        [1, 0, -7, 0]
        [2, 0, -7, 0]
        [2, 0, -7, 0]
        [2, 0, -7, 0]
        [3, 0, -7, 0]
        [3, 0, -7, 0]
        [2, 0, -7, 0]
        [1, 0, -7, 0]
        [1, 0, -7, 0]
        [0, 0, -7, 0]

        ```

        Returns
        -------
        list:
            Nested list of SCX, SCY, WX and WY for each scanline (144x4). Returns (0, 0, 0, 0) when LCD is off.
        &#34;&#34;&#34;

        if self.mb.lcd._LCDC.lcd_enable:
            return [[line[0], line[1], line[2] - 7, line[3]] for line in self.mb.lcd._scanlineparameters]
        else:
            return [[0, 0, 0, 0] for line in range(144)]

    def get_tilemap_position(self):
        &#34;&#34;&#34;
        These coordinates define the offset in the tile map from where the top-left corner of the screen is place. Note
        that the tile map defines 256x256 pixels, but the screen can only show 160x144 pixels. When the offset is closer
        to the right or bottom edge than 160x144 pixels, the screen will wrap around and render from the opposite site
        of the tile map.

        For more details, see &#34;7.4 Viewport&#34; in the [report](https://github.com/Baekalfen/PyBoy/raw/master/extras/PyBoy.pdf),
        or the Pan Docs under [LCD Position and Scrolling](https://gbdev.io/pandocs/Scrolling.html).

        Example:
        ```python
        &gt;&gt;&gt; pyboy.screen.get_tilemap_position()
        ((0, 0), (-7, 0))

        ```

        Returns
        -------
        tuple:
            Returns the tuple of registers ((SCX, SCY), (WX - 7, WY))
        &#34;&#34;&#34;
        return (self.mb.lcd.getviewport(), self.mb.lcd.getwindowpos())</code></pre>
</details>
</section>
<section>
</section>
<section>
</section>
<section>
</section>
<section>
<h2 class="section-title" id="header-classes">Classes</h2>
<dl>
<dt id="pyboy.api.screen.Screen"><code class="flex name class">
<span>class <span class="ident">Screen</span></span>
<span>(</span><span>mb)</span>
</code></dt>
<dd>
<section class="desc"><p>As part of the emulation, we generate a screen buffer in 32-bit RGBA format. This class has several helper methods
to make it possible to read this buffer out.</p>
<p>If you're making an AI or bot, it's highly recommended to <em>not</em> use this class for detecting objects on the screen.
It's much more efficient to use <code><a title="pyboy.PyBoy.tilemap_background" href="../index.html#pyboy.PyBoy.tilemap_background">PyBoy.tilemap_background</a></code>, <code><a title="pyboy.PyBoy.tilemap_window" href="../index.html#pyboy.PyBoy.tilemap_window">PyBoy.tilemap_window</a></code>, and <code><a title="pyboy.PyBoy.get_sprite" href="../index.html#pyboy.PyBoy.get_sprite">PyBoy.get_sprite()</a></code> instead.</p></section>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">class Screen:
    &#34;&#34;&#34;
    As part of the emulation, we generate a screen buffer in 32-bit RGBA format. This class has several helper methods
    to make it possible to read this buffer out.

    If you&#39;re making an AI or bot, it&#39;s highly recommended to _not_ use this class for detecting objects on the screen.
    It&#39;s much more efficient to use `pyboy.PyBoy.tilemap_background`, `pyboy.PyBoy.tilemap_window`, and `pyboy.PyBoy.get_sprite` instead.
    &#34;&#34;&#34;

    def __init__(self, mb):
        self.mb = mb

        self.raw_buffer = self.mb.lcd.renderer._screenbuffer
        &#34;&#34;&#34;
        Provides a raw, unfiltered `bytes` object with the data from the screen. Check
        `Screen.raw_buffer_format` to see which dataformat is used. **The returned type and dataformat are
        subject to change.** The screen buffer is row-major.

        Use this, only if you need to bypass the overhead of `Screen.image` or `Screen.ndarray`.

        Example:
        ```python
        &gt;&gt;&gt; import numpy as np
        &gt;&gt;&gt; rows, cols = pyboy.screen.raw_buffer_dims
        &gt;&gt;&gt; ndarray = np.frombuffer(
        ...     pyboy.screen.raw_buffer,
        ...     dtype=np.uint8,
        ... ).reshape(rows, cols, 4) # Just an example, use pyboy.screen.ndarray instead

        ```

        Returns
        -------
        memoryview:
            92160 bytes memoryview of screen data.
        &#34;&#34;&#34;
        self.raw_buffer_dims = self.mb.lcd.renderer.buffer_dims
        &#34;&#34;&#34;
        Returns the dimensions of the raw screen buffer. The screen buffer is row-major.

        Example:
        ```python
        &gt;&gt;&gt; pyboy.screen.raw_buffer_dims
        (144, 160)

        ```

        Returns
        -------
        tuple:
            A two-tuple of the buffer dimensions. E.g. (144, 160).
        &#34;&#34;&#34;
        self.raw_buffer_format = self.mb.lcd.renderer.color_format
        &#34;&#34;&#34;
        Returns the color format of the raw screen buffer. **This format is subject to change.**

        Example:
        ```python
        &gt;&gt;&gt; from PIL import Image
        &gt;&gt;&gt; pyboy.screen.raw_buffer_format
        &#39;RGBA&#39;
        &gt;&gt;&gt; image = Image.frombuffer(
        ...    pyboy.screen.raw_buffer_format,
        ...    pyboy.screen.raw_buffer_dims[::-1],
        ...    pyboy.screen.raw_buffer,
        ... ) # Just an example, use pyboy.screen.image instead
        &gt;&gt;&gt; image.save(&#39;frame.png&#39;)

        ```

        Returns
        -------
        str:
            Color format of the raw screen buffer. E.g. &#39;RGBA&#39;.
        &#34;&#34;&#34;
        self.image = None
        &#34;&#34;&#34;
        Reference to a PIL Image from the screen buffer. **Remember to copy, resize or convert this object** if you
        intend to store it. The backing buffer will update, but it will be the same `PIL.Image` object.

        Convenient for screen captures, but might be a bottleneck, if you use it to train a neural network. In which
        case, read up on the `pyboy.api` features, [Pan Docs](https://gbdev.io/pandocs/) on tiles/sprites,
        and join our Discord channel for more help.

        Example:
        ```python
        &gt;&gt;&gt; image = pyboy.screen.image
        &gt;&gt;&gt; type(image)
        &lt;class &#39;PIL.Image.Image&#39;&gt;
        &gt;&gt;&gt; image.save(&#39;frame.png&#39;)

        ```

        Returns
        -------
        PIL.Image:
            RGB image of (160, 144) pixels
        &#34;&#34;&#34;
        if not Image:
            logger.warning(&#39;Cannot generate screen image. Missing dependency &#34;Pillow&#34;.&#39;)
            self.image = utils.PillowImportError()
        else:
            self._set_image()

        self.ndarray = np.frombuffer(
            self.mb.lcd.renderer._screenbuffer_raw,
            dtype=np.uint8,
        ).reshape(ROWS, COLS, 4)
        &#34;&#34;&#34;
        References the screen data in NumPy format. **Remember to copy this object** if you intend to store it.
        The backing buffer will update, but it will be the same `ndarray` object.

        The format is given by `pyboy.api.screen.Screen.raw_buffer_format`. The screen buffer is row-major.

        Example:
        ```python
        &gt;&gt;&gt; pyboy.screen.ndarray.shape
        (144, 160, 4)
        &gt;&gt;&gt; # Display &#34;P&#34; on screen from the PyBoy bootrom
        &gt;&gt;&gt; pyboy.screen.ndarray[66:80,64:72,0]
        array([[255, 255, 255, 255, 255, 255, 255, 255],
               [255,   0,   0,   0,   0,   0, 255, 255],
               [255,   0,   0,   0,   0,   0,   0, 255],
               [255,   0,   0, 255, 255,   0,   0, 255],
               [255,   0,   0, 255, 255,   0,   0, 255],
               [255,   0,   0, 255, 255,   0,   0, 255],
               [255,   0,   0,   0,   0,   0,   0, 255],
               [255,   0,   0,   0,   0,   0, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255,   0,   0, 255, 255, 255, 255, 255],
               [255, 255, 255, 255, 255, 255, 255, 255]], dtype=uint8)

        ```

        Returns
        -------
        numpy.ndarray:
            Screendata in `ndarray` of bytes with shape (144, 160, 4)
        &#34;&#34;&#34;

    def _set_image(self):
        self.image = Image.frombuffer(
            self.mb.lcd.renderer.color_format,
            self.mb.lcd.renderer.buffer_dims[::-1],
            self.mb.lcd.renderer._screenbuffer_raw,
        )

    @property
    def tilemap_position_list(self):
        &#34;&#34;&#34;
        This function provides the screen (SCX, SCY) and window (WX, WY) position for each horizontal line in the
        screen buffer. These parameters are often used for visual effects, and some games will reset the registers at
        the end of each call to `pyboy.PyBoy.tick()`.

        See `Screen.get_tilemap_position` for more information.

        Example:
        ```python
        &gt;&gt;&gt; pyboy.tick(25)
        True
        &gt;&gt;&gt; swoosh = pyboy.screen.tilemap_position_list[66:77]
        &gt;&gt;&gt; print(*swoosh, sep=newline) # Just to pretty-print it
        [0, 0, -7, 0]
        [1, 0, -7, 0]
        [2, 0, -7, 0]
        [2, 0, -7, 0]
        [2, 0, -7, 0]
        [3, 0, -7, 0]
        [3, 0, -7, 0]
        [2, 0, -7, 0]
        [1, 0, -7, 0]
        [1, 0, -7, 0]
        [0, 0, -7, 0]

        ```

        Returns
        -------
        list:
            Nested list of SCX, SCY, WX and WY for each scanline (144x4). Returns (0, 0, 0, 0) when LCD is off.
        &#34;&#34;&#34;

        if self.mb.lcd._LCDC.lcd_enable:
            return [[line[0], line[1], line[2] - 7, line[3]] for line in self.mb.lcd._scanlineparameters]
        else:
            return [[0, 0, 0, 0] for line in range(144)]

    def get_tilemap_position(self):
        &#34;&#34;&#34;
        These coordinates define the offset in the tile map from where the top-left corner of the screen is place. Note
        that the tile map defines 256x256 pixels, but the screen can only show 160x144 pixels. When the offset is closer
        to the right or bottom edge than 160x144 pixels, the screen will wrap around and render from the opposite site
        of the tile map.

        For more details, see &#34;7.4 Viewport&#34; in the [report](https://github.com/Baekalfen/PyBoy/raw/master/extras/PyBoy.pdf),
        or the Pan Docs under [LCD Position and Scrolling](https://gbdev.io/pandocs/Scrolling.html).

        Example:
        ```python
        &gt;&gt;&gt; pyboy.screen.get_tilemap_position()
        ((0, 0), (-7, 0))

        ```

        Returns
        -------
        tuple:
            Returns the tuple of registers ((SCX, SCY), (WX - 7, WY))
        &#34;&#34;&#34;
        return (self.mb.lcd.getviewport(), self.mb.lcd.getwindowpos())</code></pre>
</details>
<h3>Instance variables</h3>
<dl>
<dt id="pyboy.api.screen.Screen.tilemap_position_list"><code class="name">var <span class="ident">tilemap_position_list</span></code></dt>
<dd>
<section class="desc"><p>This function provides the screen (SCX, SCY) and window (WX, WY) position for each horizontal line in the
screen buffer. These parameters are often used for visual effects, and some games will reset the registers at
the end of each call to <code><a title="pyboy.PyBoy.tick" href="../index.html#pyboy.PyBoy.tick">PyBoy.tick()</a></code>.</p>
<p>See <code><a title="pyboy.api.screen.Screen.get_tilemap_position" href="#pyboy.api.screen.Screen.get_tilemap_position">Screen.get_tilemap_position()</a></code> for more information.</p>
<p>Example:</p>
<pre><code class="language-python">&gt;&gt;&gt; pyboy.tick(25)
True
&gt;&gt;&gt; swoosh = pyboy.screen.tilemap_position_list[66:77]
&gt;&gt;&gt; print(*swoosh, sep=newline) # Just to pretty-print it
[0, 0, -7, 0]
[1, 0, -7, 0]
[2, 0, -7, 0]
[2, 0, -7, 0]
[2, 0, -7, 0]
[3, 0, -7, 0]
[3, 0, -7, 0]
[2, 0, -7, 0]
[1, 0, -7, 0]
[1, 0, -7, 0]
[0, 0, -7, 0]

</code></pre>
<h2 id="returns">Returns</h2>
<dl>
<dt><code>list:</code></dt>
<dd>Nested list of SCX, SCY, WX and WY for each scanline (144x4). Returns (0, 0, 0, 0) when LCD is off.</dd>
</dl></section>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@property
def tilemap_position_list(self):
    &#34;&#34;&#34;
    This function provides the screen (SCX, SCY) and window (WX, WY) position for each horizontal line in the
    screen buffer. These parameters are often used for visual effects, and some games will reset the registers at
    the end of each call to `pyboy.PyBoy.tick()`.

    See `Screen.get_tilemap_position` for more information.

    Example:
    ```python
    &gt;&gt;&gt; pyboy.tick(25)
    True
    &gt;&gt;&gt; swoosh = pyboy.screen.tilemap_position_list[66:77]
    &gt;&gt;&gt; print(*swoosh, sep=newline) # Just to pretty-print it
    [0, 0, -7, 0]
    [1, 0, -7, 0]
    [2, 0, -7, 0]
    [2, 0, -7, 0]
    [2, 0, -7, 0]
    [3, 0, -7, 0]
    [3, 0, -7, 0]
    [2, 0, -7, 0]
    [1, 0, -7, 0]
    [1, 0, -7, 0]
    [0, 0, -7, 0]

    ```

    Returns
    -------
    list:
        Nested list of SCX, SCY, WX and WY for each scanline (144x4). Returns (0, 0, 0, 0) when LCD is off.
    &#34;&#34;&#34;

    if self.mb.lcd._LCDC.lcd_enable:
        return [[line[0], line[1], line[2] - 7, line[3]] for line in self.mb.lcd._scanlineparameters]
    else:
        return [[0, 0, 0, 0] for line in range(144)]</code></pre>
</details>
</dd>
<dt id="pyboy.api.screen.Screen.raw_buffer"><code class="name">var <span class="ident">raw_buffer</span></code></dt>
<dd>
<section class="desc"><p>Provides a raw, unfiltered <code>bytes</code> object with the data from the screen. Check
<code><a title="pyboy.api.screen.Screen.raw_buffer_format" href="#pyboy.api.screen.Screen.raw_buffer_format">Screen.raw_buffer_format</a></code> to see which dataformat is used. <strong>The returned type and dataformat are
subject to change.</strong> The screen buffer is row-major.</p>
<p>Use this, only if you need to bypass the overhead of <code><a title="pyboy.api.screen.Screen.image" href="#pyboy.api.screen.Screen.image">Screen.image</a></code> or <code><a title="pyboy.api.screen.Screen.ndarray" href="#pyboy.api.screen.Screen.ndarray">Screen.ndarray</a></code>.</p>
<p>Example:</p>
<pre><code class="language-python">&gt;&gt;&gt; import numpy as np
&gt;&gt;&gt; rows, cols = pyboy.screen.raw_buffer_dims
&gt;&gt;&gt; ndarray = np.frombuffer(
...     pyboy.screen.raw_buffer,
...     dtype=np.uint8,
... ).reshape(rows, cols, 4) # Just an example, use pyboy.screen.ndarray instead

</code></pre>
<h2 id="returns">Returns</h2>
<dl>
<dt><code>memoryview:</code></dt>
<dd>92160 bytes memoryview of screen data.</dd>
</dl></section>
</dd>
<dt id="pyboy.api.screen.Screen.raw_buffer_dims"><code class="name">var <span class="ident">raw_buffer_dims</span></code></dt>
<dd>
<section class="desc"><p>Returns the dimensions of the raw screen buffer. The screen buffer is row-major.</p>
<p>Example:</p>
<pre><code class="language-python">&gt;&gt;&gt; pyboy.screen.raw_buffer_dims
(144, 160)

</code></pre>
<h2 id="returns">Returns</h2>
<dl>
<dt><code>tuple:</code></dt>
<dd>A two-tuple of the buffer dimensions. E.g. (144, 160).</dd>
</dl></section>
</dd>
<dt id="pyboy.api.screen.Screen.raw_buffer_format"><code class="name">var <span class="ident">raw_buffer_format</span></code></dt>
<dd>
<section class="desc"><p>Returns the color format of the raw screen buffer. <strong>This format is subject to change.</strong></p>
<p>Example:</p>
<pre><code class="language-python">&gt;&gt;&gt; from PIL import Image
&gt;&gt;&gt; pyboy.screen.raw_buffer_format
'RGBA'
&gt;&gt;&gt; image = Image.frombuffer(
...    pyboy.screen.raw_buffer_format,
...    pyboy.screen.raw_buffer_dims[::-1],
...    pyboy.screen.raw_buffer,
... ) # Just an example, use pyboy.screen.image instead
&gt;&gt;&gt; image.save('frame.png')

</code></pre>
<h2 id="returns">Returns</h2>
<dl>
<dt><code>str:</code></dt>
<dd>Color format of the raw screen buffer. E.g. 'RGBA'.</dd>
</dl></section>
</dd>
<dt id="pyboy.api.screen.Screen.image"><code class="name">var <span class="ident">image</span></code></dt>
<dd>
<section class="desc"><p>Reference to a PIL Image from the screen buffer. <strong>Remember to copy, resize or convert this object</strong> if you
intend to store it. The backing buffer will update, but it will be the same <code>PIL.Image</code> object.</p>
<p>Convenient for screen captures, but might be a bottleneck, if you use it to train a neural network. In which
case, read up on the <code><a title="pyboy.api" href="index.html">pyboy.api</a></code> features, <a href="https://gbdev.io/pandocs/">Pan Docs</a> on tiles/sprites,
and join our Discord channel for more help.</p>
<p>Example:</p>
<pre><code class="language-python">&gt;&gt;&gt; image = pyboy.screen.image
&gt;&gt;&gt; type(image)
&lt;class 'PIL.Image.Image'&gt;
&gt;&gt;&gt; image.save('frame.png')

</code></pre>
<h2 id="returns">Returns</h2>
<dl>
<dt><code>PIL.Image:</code></dt>
<dd>RGB image of (160, 144) pixels</dd>
</dl></section>
</dd>
<dt id="pyboy.api.screen.Screen.ndarray"><code class="name">var <span class="ident">ndarray</span></code></dt>
<dd>
<section class="desc"><p>References the screen data in NumPy format. <strong>Remember to copy this object</strong> if you intend to store it.
The backing buffer will update, but it will be the same <code>ndarray</code> object.</p>
<p>The format is given by <code><a title="pyboy.api.screen.Screen.raw_buffer_format" href="#pyboy.api.screen.Screen.raw_buffer_format">Screen.raw_buffer_format</a></code>. The screen buffer is row-major.</p>
<p>Example:</p>
<pre><code class="language-python">&gt;&gt;&gt; pyboy.screen.ndarray.shape
(144, 160, 4)
&gt;&gt;&gt; # Display &quot;P&quot; on screen from the PyBoy bootrom
&gt;&gt;&gt; pyboy.screen.ndarray[66:80,64:72,0]
array([[255, 255, 255, 255, 255, 255, 255, 255],
       [255,   0,   0,   0,   0,   0, 255, 255],
       [255,   0,   0,   0,   0,   0,   0, 255],
       [255,   0,   0, 255, 255,   0,   0, 255],
       [255,   0,   0, 255, 255,   0,   0, 255],
       [255,   0,   0, 255, 255,   0,   0, 255],
       [255,   0,   0,   0,   0,   0,   0, 255],
       [255,   0,   0,   0,   0,   0, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255, 255, 255, 255, 255, 255, 255, 255]], dtype=uint8)

</code></pre>
<h2 id="returns">Returns</h2>
<dl>
<dt><code>numpy.ndarray:</code></dt>
<dd>Screendata in <code>ndarray</code> of bytes with shape (144, 160, 4)</dd>
</dl></section>
</dd>
</dl>
<h3>Methods</h3>
<dl>
<dt id="pyboy.api.screen.Screen.get_tilemap_position"><code class="name flex">
<span>def <span class="ident">get_tilemap_position</span></span>(<span>self)</span>
</code></dt>
<dd>
<section class="desc"><p>These coordinates define the offset in the tile map from where the top-left corner of the screen is place. Note
that the tile map defines 256x256 pixels, but the screen can only show 160x144 pixels. When the offset is closer
to the right or bottom edge than 160x144 pixels, the screen will wrap around and render from the opposite site
of the tile map.</p>
<p>For more details, see "7.4 Viewport" in the <a href="https://github.com/Baekalfen/PyBoy/raw/master/extras/PyBoy.pdf">report</a>,
or the Pan Docs under <a href="https://gbdev.io/pandocs/Scrolling.html">LCD Position and Scrolling</a>.</p>
<p>Example:</p>
<pre><code class="language-python">&gt;&gt;&gt; pyboy.screen.get_tilemap_position()
((0, 0), (-7, 0))

</code></pre>
<h2 id="returns">Returns</h2>
<dl>
<dt><code>tuple:</code></dt>
<dd>Returns the tuple of registers ((SCX, SCY), (WX - 7, WY))</dd>
</dl></section>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def get_tilemap_position(self):
    &#34;&#34;&#34;
    These coordinates define the offset in the tile map from where the top-left corner of the screen is place. Note
    that the tile map defines 256x256 pixels, but the screen can only show 160x144 pixels. When the offset is closer
    to the right or bottom edge than 160x144 pixels, the screen will wrap around and render from the opposite site
    of the tile map.

    For more details, see &#34;7.4 Viewport&#34; in the [report](https://github.com/Baekalfen/PyBoy/raw/master/extras/PyBoy.pdf),
    or the Pan Docs under [LCD Position and Scrolling](https://gbdev.io/pandocs/Scrolling.html).

    Example:
    ```python
    &gt;&gt;&gt; pyboy.screen.get_tilemap_position()
    ((0, 0), (-7, 0))

    ```

    Returns
    -------
    tuple:
        Returns the tuple of registers ((SCX, SCY), (WX - 7, WY))
    &#34;&#34;&#34;
    return (self.mb.lcd.getviewport(), self.mb.lcd.getwindowpos())</code></pre>
</details>
</dd>
</dl>
</dd>
</dl>
</section>
</article>
<nav id="sidebar">
<h1>Index</h1>
<div class="toc">
<ul></ul>
</div>
<ul id="index">
<li><h3>Super-module</h3>
<ul>
<li><code><a title="pyboy.api" href="index.html">pyboy.api</a></code></li>
</ul>
</li>
<li><h3><a href="#header-classes">Classes</a></h3>
<ul>
<li>
<h4><code><a title="pyboy.api.screen.Screen" href="#pyboy.api.screen.Screen">Screen</a></code></h4>
<ul class="">
<li><code><a title="pyboy.api.screen.Screen.get_tilemap_position" href="#pyboy.api.screen.Screen.get_tilemap_position">get_tilemap_position</a></code></li>
<li><code><a title="pyboy.api.screen.Screen.tilemap_position_list" href="#pyboy.api.screen.Screen.tilemap_position_list">tilemap_position_list</a></code></li>
<li><code><a title="pyboy.api.screen.Screen.raw_buffer" href="#pyboy.api.screen.Screen.raw_buffer">raw_buffer</a></code></li>
<li><code><a title="pyboy.api.screen.Screen.raw_buffer_dims" href="#pyboy.api.screen.Screen.raw_buffer_dims">raw_buffer_dims</a></code></li>
<li><code><a title="pyboy.api.screen.Screen.raw_buffer_format" href="#pyboy.api.screen.Screen.raw_buffer_format">raw_buffer_format</a></code></li>
<li><code><a title="pyboy.api.screen.Screen.image" href="#pyboy.api.screen.Screen.image">image</a></code></li>
<li><code><a title="pyboy.api.screen.Screen.ndarray" href="#pyboy.api.screen.Screen.ndarray">ndarray</a></code></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</main>
<footer id="footer">
<p>Generated by <a href="https://pdoc3.github.io/pdoc"><cite>pdoc</cite> 0.11.5</a>.</p>
</footer>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad()</script>
</body>
</html>
